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Disclaimer 


The  US  Department  of  Commerce  makes  no  warranty,  expressed  or  implied,  to  users  of  Smokeview,  and 
accepts  no  responsibility  for  its  use.  Users  of  Smokeview  assume  sole  responsibility  under  Federal  law  for 
determining  the  appropriateness  of  its  use  in  any  particular  application;  for  any  conclusions  drawn  from  the 
results  of  its  use;  and  for  any  actions  taken  or  not  taken  as  a result  of  analyses  performed  using  these  tools. 

Users  are  warned  that  Smokeview  is  intended  for  use  only  by  those  competent  in  the  fields  of  fluid 
dynamics,  thermodynamics,  combustion,  and  heat  transfer,  and  is  intended  only  to  supplement  the  informed 
judgment  of  the  qualified  user.  The  software  package  is  a computer  model  that  may  or  may  not  have  predictive 
capability  when  applied  to  a specific  set  of  factual  circumstances.  Lack  of  accurate  predictions  by  the  model 
could  lead  to  erroneous  conclusions  with  regard  to  fire  safety.  All  results  should  be  evaluated  by  an  informed 
user. 

Throughout  this  document,  the  mention  of  computer  hardware  or  commercial  software  does  not  con- 
stitute endorsement  by  NIST,  nor  does  it  indicate  that  the  products  are  necessarily  those  best  suited  for  the 
intended  purpose. 
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User’s  Guide  for  Smokeview  Version  1 .0  - A Tool  for 
Visualizing  Fire  Dynamics  Simulation  Data 

Glenn  Forney 
Kevin  B . McGrattan 


Abstract 

Smokeview  is  a software  tool  designed  to  visualize  numerical  predictions  generated  by  the  NIST  Fire 
Dynamics  Simulator  (FDS).  FDSis  a computational  fluid  dynamics  (CFD)  model  of  fire-driven  fluid  flow. 
These  two  tools  are  used  in  concert  to  respectively  model  and  analyze  scenarios  involving  features  such  as 
fire,  wind,  sprinklers,  complex  geometry  etc.  Smokeview  visualizes  FDS  modeling  results  in  many  ways, 
some  of  which  are  1 ) animating  flow  of  smoke  or  tracer  particles,  2)  animating  2D  contours  of  data  slices, 
3)  plotting  2D  and  3D  static  contours  or  4)  plotting  flow  vectors  . 

Smokeview  requires  a fast  CPU.  fast  video  card,  a substantial  amount  of  random-access  memory  (RAM) 
and  a large  hard  disk.  Smokeview  is  portable  and  can  be  run  on  a variety  of  computing  platforms.  For  a 
Windows-based  PC,  the  processor  should  be  at  least  a 450  MHz  Pentium  II.  with  at  least  256  Mbytes  of 
memory.  Of  course,  more  is  better,  but  this  configuration  should  allow  one  to  do  fairly  large  calculations  in 
a reasonable  time  period.  For  UNIX-based  workstations,  the  processor  and  memory  should  be  at  least  as 
fast  and  as  large  as  the  PC  specs. 

Smokeview  and  FDS  may  be  obtained  at  the  web  site  http://fire.nist.gov/smokeview  or  by  contacting 
the  authors  at  glenn . f orney@nist . gov  or  kevin  . mcgrattan@nist . gov. 


1 Overview 

Smokeview  is  a software  tool  designed  to  visualize  numerical  predictions  generated  by  the  NIST  Fire  Dy- 
namics Simulator  (FDS),  a computational  fluid  dynamics  (CFD)  model  of  fire-driven  fluid  flow.  FDS[1,  2,  3] 
and  Smokeview  are  used  in  concert  to  respectively  model  and  visualize  fire  scenarios  of  interest.  Smokeview 
performs  this  visualization  by  presenting:  smoke  or  tracer  particle  flow  (particle  files);  animated  (in  time) 
contour  slices  of  computed  gas  quantities  (slice  files)  and  surface  data  (boundary  files);  and  static  contour 
and  vector  plots  (PL0T3D  files)  anywhere  within  a simulation  scene  at  a single  fixed  time. 

Normally  Smokeview  is  used  in  a post-processing  step  to  visualize  FDS  data  after  a calculation  has 
completed.  Smokeview  may  also  be  used  during  a calculation  to  monitor  a simulation's  progress  and  before  a 
calculation  to  visualize  blockage,  vent,  sprinkler  and/or  heat  detector  locations  etc.  in  order  to  set  up  correct 
FDS  input  files  more  quickly. 

Figure!  illustrates  how  the  data  files  used  by  the  NIST  Fire  Dynamics  Simulator  and  Smokeview  are 
related.  A typical  procedure  for  using  FDS  and  Smokeview  is  to: 

1 . Set  up  an  FDS  input  file,  a file  with  a .data  extension.  Reference  [2]  gives  documentation  on  FDS  input 
data  files. 

2.  Run  FDS.  The  fire  model  FDS  then  creates  one  or  more  output  files  with  extensions  . smv,  .part, 
. sf , . q,  . bf  . 

3.  Run  Smokeview  to  analyze  the  output  files  generated  by  step  2. 

This  report  documents  step  3.  Steps  1 and  2 are  documented  in  reference  [2], 
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Figure  1 : Diagram  illustrating  data  files  and  programs  used  in  the  NIST  Fire  Dynamics  System  (FDS) 


Particle,  slice,  boundary  and  PLOT3D  files  may  be  loaded  into  Smokeview  by  clicking  the  right-mouse 
button  and  selecting  the  appropriate  Load/Unload  menu  option.  Other  menu  options  are  discussed  in  Ap- 
pendix A.  Many  menu  commands  may  also  be  executed  using  keyboard  shortcuts.  These  shortcuts  are  listed 
and  explained  in  Smokeview’s  help  menu  item  and  Appendix  C.  Visualization  attributes  not  controllable 
through  the  menus  (for  example,  data  minimums  and  maximums)  may  be  changed  by  using  the  Smokeview 
customization  file  named  smokeview.  ini  which  is  discussed  in  Appendix  D.  1. 

Smokeview  is  written  using  the  3D  graphics  library  OpenGL[4]  and  the  Graphics  Library  Utility  Toolkit 
(GLUT)[5].  Implementing  a full  fledged  graphical  user  interface  (GUI)  is  a daunting  task.  Using  GLUT 
allows  one  to  create  simple  GUI  applications  with  minimal  effort  so  that  most  of  the  development  can  be 
spent  on  implementing  the  visualizations  rather  than  the  creating  an  elaborate  user  interface.  In  addition, 
GLUT  applications  are  portable.  Currently,  Smokeview  runs  on  the  PC  under  Windows  95/98/NT/2000  and 
on  several  UNIX  workstations  including  SGI/IRIX,  IBM/AIX,  SUN/Solaris,  HP/UX  and  Redhat  LINUX. 


2 Getting  Started 

Smokeview  may  be  obtained  at  the  web  site  http://fire.nist.gov/smokeview . This  site  gives  links  to  a Setup 
program  for  PC  installation.  It  also  contains  documentation  for  Smokeview  and  FDS,  sample  FDS  calcula- 
tions, software  updates  and  mechanisms  for  providing  feedback  about  the  software. 

After  obtaining  the  setup  program,  install  Smokeview  on  the  PC  by  either  entering  the  setup  program 
name  from  the  Windows  Start/Run . . . menu  or  by  double-clicking  on  the  downloaded  Smokeview  setup 
program.  The  setup  program  then  steps  through  the  program  installation.  It  copies  the  Smokeview  executable, 
the  GLUT  graphics  libraries  and  the  Smokeview  preference  file  smokeview.  ini  to  the  default  directory 
c:\nist\fds  . The  setup  program  also  defines  PATH  variables  and  associates  the  . smv  file  extension  to 
the  Smokeview  program  so  that  one  may  either  type  smokeview  at  any  command  line  prompt  or  double 
click  on  any  . smv  file.  The  installation  program  assumes  that  OpenGL  has  been  installed  which  is  true  for 
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all  but  the  very  first  release  of  Windows  95. 1 Windows  98,  2000,  NT  4.0  and  all  later  versions  of  Windows 
95  contain  the  OpenGL  libraries. 


3 Using  Smokevievv 

Smokeview  may  be  started  on  the  PC  by  double-clicking  the  file  named  casename  . smv  where  casename 
is  the  name  specified  by  the  CHID  keyword  defined  in  the  FDS  input  data  file.  The  Load/Unload  may 
be  used  to  read  in  the  data  files  to  be  visualized.  The  Show/Hide  menu  may  be  used  to  change  how  the 
visualizations  are  presented.  For  the  most  part,  the  menu  choices  are  self  explanatory.  Menu  items  exist  for 
showing  and  hiding  various  simulation  elements,  creating  GIF  screen  dumps,  obtaining  help  etc.  Menu  items 
are  described  in  Appendix  A. 

To  use  Smokeview  from  a “command  line”,  open  a DOS  (if  running  on  a PC)  or  UNIX  shell,  change  to 
the  directory  containing  the  FDS  case  to  be  viewed  and  type: 

smokeview  casename 

where  again  casename  is  the  name  specified  by  the  CHID  keyword  defined  in  the  FDS  input  data  file. 

Normally  Smokeview  is  run  after  an  FDS  case  has  completed.  Smokeview  may  also  be  used  as  an  aid 
in  setting  up  FDS  cases  by  visualizing  geometric  components  such  as  blockages,  vents,  sensors,  etc.  One  can 
then  verify  that  these  modeling  elements  have  been  defined  and  located  as  intended.  One  may  select  the  color 
of  these  elements  using  color  parameters  in  the  smokeview . ini  file  to  help  distinguish  one  element  from 
another. 

3.1  Data  Files 

FDS  generates  several  data  files  visualized  by  Smokeview.  Each  file  type  may  be  loaded  or  unloaded  using 
the  Load/Unload  menu  described  in  Appendix  B.2.  These  data  files  are: 


Particle  files  Particle  files  contain  the  locations  of  the  thermal  elements  (or  particles)  used  to  introduce 
heat  from  the  fire  or  to  visualize  the  flow  field.  Particles  are  colored  using  criteria  such  as: 
1)  temperature,  2)  burning  state:  burning,  burned  out,  or  3)  whether  they  are  water  (sprinkler 
droplets).  Temperature  colors  are  selected  from  a user  definable  color  palette  defined  with  the 
COLOR  keyword  documented  in  Appendix  D.l.  Figure  2 shows  a snapshot  of  particle  flow 
where  particles  are  colored  according  to  their  temperature.  Default  colors  for  other  quantities 
are  yellow  for  burning,  white  for  non-burning,  and  blue  for  water  droplets.  Particles  are  stored 
in  files  ending  with  the  extension  .part  . Particle  files  are  displayed  by  selecting  the  desired 
particle  file  from  the  Load/Unload  menu. 

Slice  files  Slice  files  contain  data  recorded  within  a rectangular  array  of  grid  points  at  each  recorded  time 
step.  Continuously  shaded  contours  are  drawn  for  simulation  quantities  such  as  temperature, 
gas  velocity  and  heat  release  rate.  All  or  part  of  a plane  is  selected  when  setting  up  the  FDS 
input  data  file.  Figure  3 shows  a snapshot  of  a slice  file  where  the  slice  is  colored  according  to 
gas  temperature.  Slice  files  have  file  names  with  extension  . sf  . Slice  files  are  displayed  by 
selecting  the  desired  slice  file  from  the  Load/Unload  menu. 

Boundary  Files  Boundary  files  contain  simulation  data  recorded  at  interior  or  exterior  boundary  sur- 
faces. Continuously  shaded  contours  are  drawn  for  quantities  such  as  wall  surface  temperature, 
radiative  flux  etc.  Figure  4 shows  a snapshot  of  a boundary  file  animation  where  the  surfaces 
are  colored  according  to  their  temperature.  Boundary  files  have  file  names  with  extension  . bf . 

'Though  the  OpenGL  libraries  could  be  found  on  the  Internet  and  installed  on  a PC  running  the  first  release  of  Windows  95,  it  is 
recommended  that  Windows  be  upgraded  to  a more  current  release. 
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Frame:  5 
Time:  2.5 


Figure  2:  Particle  File  Example. 


Figure  3:  Slice  File  Example 
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NIST  Smokeview  1 0 0 


Figure  4:  Boundary  File  Example 


Boundary  files  are  displayed  by  selecting  the  desired  boundary  file  from  the  Load/ Unload 
menu. 

PLOT3D  files  PLOT3D  files  store  five  data  values  at  each  grid  cell.  FDS  stores  temperature,  three  com- 
ponents of  velocity  (U,  V,  W)  and  heat  release  rate  by  default.  Other  quantities  may  be  stored 
if  desired.  In  addition  the  PLOT3D  format  allows  one  to  specify  internal  blockages  so  that 
contour  data  need  not  be  displayed  where  the  physical  domain  is  blocked  off.  PLOT3D[6]  files 
store  data  in  a standard  format  developed  by  NASA  and  used  by  many  CFD  programs  for  rep- 
resenting simulation  results.  An  FDS  simulation  will  typically  create  PLOT3D  files  at  several 
times.  PLOT3D  data  is  visualized  in  three  ways:  as  2D  contours,  vector  plots  and  iso-surfaces. 
2D  contours2  along  either  of  the  XZ,  XY  or  YZ  planes.  In  the  default  Smokeview  view,  the  X 
and  Z coordinate  axes  are  parallel  to  the  horizontal  and  vertical  screen  edges  respectively  while 
the  Y coordinate  axis  occurs  front  to  back  “within"  the  screen.  Figure  5 shows  an  example  of 
a 2D  PLOT3D  contour.  Vector  plots  may  be  viewed  if  one  or  more  of  the  U,V  and  W velocity 
components  are  stored  in  the  PLOT3D  file.  The  vector  length  and  direction  show  the  direction 
and  speed  of  fluid  flow  travel  while  the  vector  colors  show  the  solution  value.  Figure  6 show 
vectors  which  indicate  flow  direction.  3D  contours  or  iso-surfaces  show  where  the  solution  at- 
tains one  particular  value.  Figure  7 gives  an  example  of  an  iso-surface.  PLOT3D  data  are  stored 
in  files  with  extension  . q . 


The  format  used  to  store  each  of  the  above  data  files  are  given  in  Appendix  D.3  so  that  Smokeview  may  be 
used  to  visualize  data  generated  by  other  fire  models. 


2 2D  contours  may  be  shaded  continuously  as  are  slice  and  boundary  file  data  or  shaded  in  discrete  shades  of  uniform  color. 
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NIST  Smoke  view  1 0.0,  roomfire_0025_00.q 


rioted 

TEMP 

C 


215 

195 


I 


175 

155 

135 

115 

95.0 


75.0 


55.0 


35.0 


15.0 


XZ:  2 


Figure  5:  PLOT3D  Contour  Example 
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Figure  6:  PLOT3D  Vector  Plot  through  a door 
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Figure  7:  PLOT3D  Iso-contour  Example 


3.2  Visualizing  FDS  Output 

3.2.1  Mouse  movement 

The  left  mouse  button  is  used  to  either  rotate  or  translate  the  scene  depending  upon  whether  the  SHIFT,  CTRL 
or  ALT  keys  are  depressed  or  not  during  mouse  movement.  Figure  8 shows  an  outline  view  of  a Smokeview 
scene  with  X,  Y and  Z axes  labeled.  Again  note  that  in  the  default  Smokeview  view,  the  X and  Z coordinate 
axes  are  parallel  to  the  horizontal  and  vertical  screen  edges  respectively  while  the  Y coordinate  axis  occurs 
front  to  back  “within”  the  screen.  Left  and  right  scene  motion  occurs  along  the  X axis,  up  and  down  scene 
motion  occurs  along  the  Y axis  while  in  and  out  scene  motion  occurs  along  th  Z axis.  These  labels  are  used 
to  describe  how  the  mouse  effects  scene  movement  in  the  following  way: 


No  modifier  key  depressed  Horizontal! vertical)  mouse  movement  results  in  scene  rotation  parallel  to 
the  XY  (YZ)  plane.  Rotation  parallel  to  the  YZ  plane  is  disabled  while  eye  view  is  in  effect.  The 
view  is  switched  between  eye  view  and  world  view  by  either  depressing  the  e key  or  by  selecting 
the  Show/ Hide  view  menu  item.  Equivalently,  horizontal! vertical)  mouse  movement  results 
in  scene  rotation  about  the  Z(X)  axis. 

SHIFT  key  depressed  Horizontal! vertical)  mouse  movement  results  in  scene  rotation  parallel  to  the 
XZ(YZ)  plane.  Equivalently,  horizontal! vertical)  mouse  movement  results  in  scene  rotation 
about  the  Y(X)  axes  respectively. 

CTRL  key  depressed  Horizontal  mouse  movement  results  in  scene  translation  from  side  to  side  along 
the  X axis.  Vertical  mouse  movement  results  in  scene  translation  “in  and  out”  of  the  computer 
screen  along  the  Y axis. 

ALT  key  depressed  Vertical  mouse  movements  results  in  scene  translation  along  the  Z axis.  Horizontal 
mouse  movement  has  no  effect  on  the  scene. 
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Figure  8:  Smokeview  coordinate  system. 

Note  that  the  Reset  View  menu  item  resets  the  scene  back  to  the  original  view. 

3.2.2  Particle,  slice,  boundary  file  visualization 

Particle,  slice  and  boundary  files  are  straightforward  to  visualize.  Once  Smokeview  has  started  up,  simply 
select  the  desired  file  from  the  Load/ Unload  menu  and  view  the  scene. 

Particle  files  are  typically  much  larger  than  other  output  files.  Several  strategies  exist  for  reducing  the 
memory  required  to  display  particle  files.  All  of  these  strategies  involve  modifying  various  keywords  found 
in  the  Smokeview  preference  files.  The  Smokeview  preference  file  smokeview.  ini  may  be  created  by 
typing  “smokeview  -ini”  at  a command  line  or  by  selecting  the  Init  File  sub-menu  of  the  the 
Load/ Unload  menu.  These  preference  file  keywords  with  default  values  are  given  below  and  are  doc- 
umented in  Appendix  D.l . 

MAXFRAMES 

501 

MAXPOINTS 

5000000 

PARTPOINTSTEP 

1 

PARTPOINTCOMPRESS 

2 

PARTFRAMESTEP 

1 

The  MAXFRAMES  and  MAXPOINTS  keywords  determine  the  maximum  number  of  data  frames  and  data 
points  used  to  read  in  particles.  These  two  parameters  may  also  be  set  from  the  command  line  when  starting 
up  Smokeview.  The  PARTPOINTSTEP  and  PARTFRAMESTEP  parameters  allow  one  to  skip  particles  or 
particle  frames.  Finally,  the  PARTPOINTCOMPRESS  allows  one  to  store  particle  data  in  a compressed 
format.  Setting  PARTPOINTSTEP  and  PARTFRAMESTEP  to 
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PARTPOINTSTEP 

3 

PARTFRAMESTEP 

3 

reduces  the  memory  needed  by  a factor  of  nine  since  every  third  point  and  every  third  particle  frame  instead 
of  all  points  and  frames  are  loaded. 

Sometimes  it  is  of  interest  to  change  the  minimum  and  maximum  axis  labels,  for  example  to  use  the  same 
min  and  max  for  each  loaded  data  file.  Data  value  bounds  may  be  set  with  the  V-PARTICLES,  V_SLICE 
and  V _B 0 UND AR Y keywords.  The  default  values  are  given  by 

V_PARTICLES 
0 1.000000  0 0.000000 
V_SLICE 

0 1.000000  0 0.000000 
V_BOUNDARY 

0 1.000000  0 0.000000 

To  cause  Smokeview  to  set  the  min  and  max  labels  to  30  and  600  respectively  use 
V_PARTICLES 

1 30.000000  1 600.000000 
V_SLICE 

1 30.000000  1 600.000000 
V_BOUNDARY 

1 30.000000  1 600.000000 

The  integer  “1”  occuring  before  the  “3  0”  or  “6  0 0”  causes  Smokeview  to  use  the  next  number  as  a minimum 
or  maximum  value  respectively.  If  this  integer  is  0 then  Smokeview  ignores  the  subsequent  min/max  value. 

3.2.3  Visualizing  PLOT3D  data  files 

PLOT3D  files  are  more  complicated  to  visualize  than  files  containing  time  dependent  data  such  as  particle, 
slice  or  boundary  files.  For  example,  only  the  transparency  and  color  characteristics  of  a time  file  may  be 
changed.  With  PLOT3D  files  however,  many  attributes  may  be  changed.  One  may  view  2D  contours  along 
the  X,  Y and/or  Z axis  of  up  to  six3  different  simulated  quantities,  view  flow  vectors  and  iso  or  3D  contours. 
PLOT3D  file  visualization  is  initiated  by  selecting  the  desired  file  from  the  Load/Unload  PLOT3D  sub- 
menu and  as  with  time  files  one  may  change  color  and  transparency  characteristics. 


2D  contours  Smokeview  displays  the  “middle”  2D  contour  along  the  Y axis  by  default  when  a PLOT3D 
file  is  first  loaded.  To  step  the  contour  slice  up  by  one  grid  cell  along  the  Y axis,  depress 
the  “space  bar”.  Similarly  to  step  the  contour  slice  down  by  one  grid  cell  along  the  Y axis, 
depress  the  “-”  key.  The  “x”,  “y”  or  “z”  keys  toggle  contour  visibility  along  the  X,  Y and  Z axes 
respectively.  The  PLOT3D  variable  viewed  may  be  changed  by  either  depressing  the  “p”  key 
or  by  selecting  the  Solution  Variable  sub-menu  of  the  Show/Hide  menu.  Minimum 
and  maximum  PLOT3D  values  may  be  set  using  the  V_PLOT3D  smokeview.  ini  keyword. 
The  default  V_PLOT3D  keyword  value  is  given  by 

V_PLOT3D 

3The  FDS  software  stores  temperature,  three  components  of  velocity  (denoted  U , V and  W)  and  heat  release  per  unit  volume.  If  at 
least  one  velocity  component  is  stored  in  a PLOT3D  file  then  Smokeview  adds  speed  to  the  PLOT3D  variable  list. 
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5 

1 0 1.0  0 0.0 

2 0 1.0  0 0.0 

3 0 1.0  0 0.0 

4 0 1.0  0 0.0 

5 0 1.0  0 0.0 


where  the  initial  5 indicates  the  number  of  subsequent  bound  lines.  Each  bound  line  begins  with 
an  integer  (indicating  the  PFOT3D  variable  number)  followed  by  4 numbers  defined  the  same 
as  with  the  V.PARTTCLE,  V.SLICE  and  VJ30UNDARY  keywords.  To  set  the  minimum  and 
maximum  bound  for  the  first  PLOT3D  variable  to  20  and  620  use 


V_PLOT3D 

5 

1 1 20.0  1 620.0 

20  1.0  0 0.0 

3 0 1.0  0 0.0 

4 0 1.0  0 0.0 

5 0 1.0  0 0.0 


Smokeview  then  uses  these  bounds  to  label  the  PLOT3D  color  bar  from  20  to  620.  It  draws  con- 
tours smaller  than  20  with  the  “smallest”  color  and  contours  bigger  than  620  with  the  “biggest” 
color.  In  addition  to  0 and  1,  the  V_PLOT3D  keyword  may  use  2 as  a bound  indicator  . In  the 
above  example,  if  2 rather  than  1 is  used  to  define  PLOT3D  bounds,  then  Smokeview  does  not 
draw  contour  levels  smaller  than  20  or  contours  greater  than  620.  This  is  true  for  "stepped”  or 
discrete  contours.  If  “continuous”  contours  are  drawn  then  “2”  and  “1”  have  the  same  effect. 
Figure  9 shows  a ceiling  jet  contour  plot  drawn  using  the  following  V_PLOT3D  values 


V_PLOT3D 

5 

1 2 300.0  1 350.0 

2 0 1.0  0 0.0 

3 0 1.0  0 0.0 

4 0 1.0  0 0.0 

5 0 1.0  0 0.0 


The  bound  line  1 2 300.0  1 350.0  indicates  that  temperatures  below  300  ° C are  not 
drawn  and  that  temperatures  above  350  ° C are  drawn  with  the  “highest”  color  (black  in  black 
and  white  mode,  red  in  color  mode). 


Flow  vectors  If  at  least  one  velocity  component  is  present  in  the  PLOT3D  file  then  the  “v”  key  may  be 
depressed  in  order  to  view  flow  vectors.  The  length  and  direction  of  the  vector  indicates  the  flow 
direction  and  speed.  The  vector  color  indicates  the  value  of  the  currently  displayed  quantity.  A 
small  dot  is  drawn  at  the  end  of  the  line  to  indicate  flow  direction.  The  vector  lengths  as  drawn 
may  be  changed  by  depressing  the  “a”  key.  Vector  plots  may  be  very  dense  when  the  grid  is 
finely  meshed.  The  “s”  key  may  be  depressed  in  order  to  skip  vectors.  For  example,  all  vectors 
are  displayed  by  result.  If  the  “s”  key  is  depressed,  then  every  other  vector  is  skipped. 
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Figure  9:  Contour  plot  illustrating  a ceiling  jet  by  using  a V_PLOT3D  keyword  entry  of:  “1  2 3 00.0  1 
3 50.0”  for  the  first  (temperature)  PLOT3D  variable. 


Iso-Contours  Iso-contours  also  called  3D  contours  or  level  surfaces  may  be  viewed  by  depressing  the 
“i  key  or  by  selecting  the  PLOT3D  3D  Contours  sub-menu  of  the  Show/Hide  menu. 


3.3  Checking  FDS  Input 

Consider  the  following  FDS  input  file.  It  describes  a small  space  with  a burner  adjacent  to  the  near  wall,  a 
small  vent  on  the  opposite  wall  and  an  interior  wall  containing  a door.  Figure  1 0 is  a Smokeview  visualization 
of  this  input  file.  Using  Smokeview  one  may  conclude  that  a blockage  and  vent  are  not  in  their  intended 
locations. 

&HEAD  CHID= ' testcasel ' , TITLE= ' Single  Fire  Plume'  / 

&GRID  IBAR=32 , JBAR=32 , KBAR=32  / 

&PDIM  XBAR=1 . 0 , YBAR=1 . 0 , ZBAR=1 . 0 / 

&TIME  DT=0 . 05 , TWFIN=0 . 05  / 

&SURF  ID= 'burner ' , VEL=- . 2 , PARTICLES= . TRUE . , PARTICLE_COLOR= ' RED ' / 

&SURF  ID= ' inlet ' , VEL=- . 2 , PARTICLES= . TRUE . , PARTICLE_COLOR= ' GREEN ' / 

&OBST  XB=0 . 65, 0 . 85 , 0 . 00 , 0 . 2 , 0 . 1 , 0 . 2 , BLOCK_COLOR= 'GREEN'  / 

&OBST  XB=0 . 00, 0 . 30 , 0 . 45 , 0 . 5 , 0 . 0 , 1 . 0 / 

&OBST  XB=0. 70, 1.00, 0.45, 0.5, 0.0, 1.0  / 

&OBST  XB=0 . 30, 0 . 60, 0 . 45 , 0 . 5, 0 .7 , 1 . 0 , BLOCK_COLOR= ' BLUE ' / 

&VENT  XB=0 . 70, 0 . 8 , 0 . 05, 0 . 15, 0 .2 , 0 . 2 , SURF_ID= 'burner ' / 

&VENT  XB=0 .65,0.85,1.00,1.0,0.2,0.4, SURF_ID= ' inlet ' / 

This  input  file  contains  two  errors  as  can  be  noted  by  examining  Figure  10.  First,  the  door  soffit  (the  blue 
blockage)  contains  an  unintended  gap,  second  the  burner  vent  does  not  completely  cover  the  underlying 
(GREEN)  blockage.  Note  that  it  is  certainly  permissible  to  define  a vent  this  way  but  for  the  purposes  of 
this  example  it  was  intended  that  the  vent  cover  the  entire  blockage.  Blockages  may  be  individually  colored 
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NIST  Smokeview  1 0 0 


Figure  10:  Using  Smokeview  to  verify  model  input.  This  example  has  a gap  in  the  door  soffit  and  a burner 
vent  boundary  that  is  too  small. 


in  order  to  associate  &OBST  lines  in  an  FDS  data  file  with  blockages  in  the  Smokeview  scene.  The  blue 
blockage  may  be  corrected  replacing  the  above  blue  OBST  line  with 

&OBST  XB=  0 .30,0.70,0.45,0.5,0.7,1.0, BLOCK_COLOR= ' BLUE ' / 

The  burner  vent  may  be  corrected  by  matching  the  horizontal  vent  coordinates  with  the  horizontal  “GREEN” 
blockage  coordinates  and  replacing  the  ‘burner’  vent  line  in  the  above  case  with 

&VENT  XB=0 .65,0.85,0.00,0.20,0.2,0.2, SURF_ID= ' burner ' , VENT_CO LOR =' GREEN ' / 
Figure  1 1 shows  a view  of  the  corrected  test  case. 

The  following  is  a general  procedure  for  identifying  problems  in  FDS  input  files.  Assume  that  the  FDS 
input  data  file  is  named  testcasel . data. 

1 . Set  SET_UP=  . TRUE . on  the  &MISC  line.  This  causes  FDS  to  read  the  input  file  and  create  a . smv 
file  without  running  the  case. 

2.  After  the  input  file  has  been  modified,  run  the  FDS  model  by  typing: 
fds  < testcasel . data 

FDS  creates  a file  named  testcasel . smv  containing  information  that  Smokeview  uses  to  visualize 
data. 

3.  To  visualize  the  input  file,  open  testcasel . smv  with  Smokeview  by  either  typing  smokeview 
testcasel  at  a command  shell  prompt  or  if  on  the  PC  by  double-clicking  the  file  testcasel . smv. 

If  Smokeview  was  already  running  {i.e.  from  an  earlier  iteration  in  this  debugging  cycle)  re-read 
testcasel . smv  into  Smokeview  with  the  Reload  testcasel . smv  menu  item. 
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NIST  Smokeview  1 0 0 


Figure  1 1 : Corrected  case 


4.  Make  corrections  if  necessary.  Use  the  BLOCK_COLOR  option4  of  the  FDS  keyword  OBST  to  more 
easily  identify  blockages  to  be  edited.  Save  testcasel  .data  file  and  go  back  to  step  2. 

5.  If  corrections  were  not  necessary,  then  change  the  TWFIN  keyword  back  to  the  desired  final  simulation 
time,  remove  any  unnecessary  FDS  BLOCK_COLOR,  VENT -COLOR  and  SET.UP  keywords  and  run  the 
case. 


4 The  FDS  BLOCK-COLOR  and  VENT-COLOR  keywords  may  have  values:  RED,  BLUE,  GREEN,  MAGENTA,  CYAN,  YELLOW,  WHITE 
or  BLACK. 
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A Smokeview  Command  Line  Options 


Smokeview  may  be  run  from  a command  shell.  Further,  command  line  options  may  be  invoked  in  order  to 
alter  Smokeview’s  startup  behavior.  Normally  these  options  are  not  necessary.  However,  they  may  be  used 
for  cases  with  very  large  particle  files  or  to  generate  a preference  or  customization  file.  To  obtain  a list  of 
command  line  options,  type: 

smokeview 

without  any  arguments  which  results  in  output  similar  to: 


Smokeview  1.0.0  - Release  Jan  1 2000  - NIST/BFRL 

Visualize  fire/smoke  flow  simulations.  All  parameters  are  optional. 
Usage : 

smokeview  casename  -points  m -frames  n -ini  -nopart  -benchmark 


where 


casename 

m 

n 

-ini 

-nopart 

-benchmark 


project  id  (file  names  without  the  extension) 
maximum  number  of  particles.  Default=5000000 
maximum  number  of  particle  frames.  Default=501 
output  default  smokeview  parameters  to  smokeview.ini 
do  not  load  particle  file 
display  graphics  performance  indicators 


The  -nopart  option  is  used  to  prevent  a particle  file  from  being  loaded  at  startup  as  in: 
smokeview  casename  -nopart 

The  -points  or  -frames  options  may  be  used  to  load  more  than  the  default  5,000,000  points  or  500 
frames  where  a frame  is  data  for  one  time  step.  To  load  up  to  6,000,000  points  and  1000  frames  then  type: 

smokeview  casename  -points  6000000  -frames  1000 

where  in  both  cases  casename  is  the  basename  of  the  FDS  output  files.  The  same  effect  may  be  achieved 
by  using 

MAXPOINTS 

6000000 

MAXFRAMES 

1000 

in  the  smokeview.ini  or  casename.ini  file.  This  file  may  be  created  with  the  -ini  option  and 
contains  many  other  customizable  Smokeview  parameters.  The  -benchmark  option  is  used  to  measure 
the  performance  of  Smokeview.  When  particle  files  are  displayed  Smokeview  outputs  the  rate  that  points 
(particles)  are  displayed  per  second.  Similarly,  when  iso-surfaces  (3D  PLOT3D  contours)  are  displayed  the 
-benchmark  option  causes  Smokeview  to  output  the  rate  that  triangles  are  displayed  per  second. 
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B Menu  Options 


The  design  philosophy  used  to  develop  Smokeview  has  been  to  avoid  complicated,  non-portable  user  inter- 
faces that  are  costly  to  implement.  As  a result,  most  of  the  development  effort  has  gone  into  the  visualization 
(display  of  particle  flow,  contour  plots  etc ) rather  than  user  interface  design  and  implementation.  The  graph- 
ics library  utility  toolkit  GLUT[5]  based  on  OpenGL[4]  is  used  to  implement  the  “pop  up”  menus  used  by 
Smokeview  to  manipulate  various  features  of  the  graphical  scenes.  The  user  interacts  with  Smokeview  via  1 ) 
menus,  2)  keyboard  shortcuts  and  3)  the  . ini  file. 

A “pop  up”  menu  is  displayed  when  the  right  mouse  is  clicked  anywhere  within  the  scene.  The  main 
menu  options  are:  Load/Unload  , Show/Hide,  Max  Frame  Rate,  Render,  Tour,  Reset  View, 
Help  and  Quit.  Several  of  these  menu  options  have  sub-menus.  These  options  are  explained  in  the  follow- 
ing sections. 


B.l  Main  Menu  Items 

Load/Unload  This  option  allows  one  to  load  or  unload  particle,  slice,  PLOT3D  or  boundary  files.  The 
three  time  dependent  files  (particle,  slice  and  boundary)  may  be  viewed  simultaneously,  but  not 
concurrently  with  the  time  independent  PLOT3D  files.  However,  only  one  particle,  one  slice, 
one  boundary  and  one  PLOT3D  file  may  be  viewed  at  a time.  This  menu  may  also  be  used  to 
load  and  create  preference  files  . ini  files  and  to  re-read  the  . smv  file.  For  more  details 
see  Appendix  B.2. 

Show/Hide  This  menu  item  allows  one  to  show  or  hide  the  loaded  data  files  and  various  scene  attributes 
such  as  time/color  bars,  internal  blockages  etc.  As  a file  type  is  shown  or  hidden  (or  loaded  and 
unloaded),  the  color  and  time  bars  are  changed  to  reflect  the  currently  visible  data  files.  More 
details  are  given  in  Appendix  B.3. 


Max  Frame  Rate  This  option  controls  the  rate  at  which  image  frames  are  displayed.  The  sub-menus 
allow  one  to  specify  a maximum  frame  rate.  The  actual  frame  rate  may  be  slower  if  the  scene  is 
complex.  The  unlimited  menu  item  allows  one  to  display  frames  as  rapidly  as  the  graphics 
hardware  permits  or  to  step  through  the  frames  manually.  The  step  menu  item  allows  one  to 
step  through  the  simulation  one  time  step  at  a time.  This  menu  item  may  be  used  in  concert 
with  the  Render  menu  item  described  below  to  create  images  at  the  desired  time  and  view 
orientation  for  inclusion  into  reports.  This  is  how  figures  were  generated  in  this  report. 


Render  This  option  allows  one  to  create  GIF  files  of  the  currently  displayed  scene.  The  Render  sub- 
menus allow  one  to  specify  an  integer  between  1 and  20  indicating  the  number  of  frames  be- 
tween rendered  GIF  images.  This  allows  one  to  generate  GIF  images  encompassing  the  en- 
tire time  duration  of  the  simulation  which  in  turn  can  be  converted  into  movie  files  (mpeg, 
mov,  avi  etc)  using  software  available  on  the  Internet.  This  is  how  movies  were  displayed 
http://fire.nist.gov/smokeviewwere  generated.  Rendering  may  be  stopped  by  selecting  Cancel 
(Keyboard  shortcut  for  the  render  option:  r) 

Tour  Causes  the  scene  to  rotate  about  its  center. 

Reset  Resets  the  simulation  scene  back  to  the  original  view.  If  a time  file  (particle,  slice  and/or  bound- 

ary) is  visible  then  two  sub-menus  occur  allowing  one  to  reset  the  view  back  to  the  original 
position  or  the  time  bar  back  to  the  initial  time. 
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Help 


Displays  a list  and  explanation  of  keyboard  equivalent  commands 


Quit  Exit  or  quit  Smokeview. 


B.2  Load/Unload 

Four  types  of  files  may  be  visualized  with  Smokeview.  They  are  particle,  slice,  boundary  and  PFOT3D  files. 
The  format  of  the  data  contained  in  these  files  is  described  in  Appendix  D.3.  A sub-menu  is  present  under 
Load/Unload  for  each  file  type  generated  for  the  simulation.  Selecting  one  of  the  files  appearing  in  the 
sub-menu  causes  it  to  be  loaded  and  then  displayed.  The  data  may  be  unloaded  or  freed  by  selecting  an 
Unload  menu  item  appearing  under  the  file  list.  Selecting  Unload  All,  as  expected,  will  unload  all  files. 
If  the  wish  is  to  temporarily  hide  a data  file,  then  the  appropriate  Show/ Hide  menu  option  (depending  on 
the  file  type  to  be  hidden)  should  be  selected. 

The  Smokeview  input  data  file  contains  information  about  all  data  files  appearing  in  the  Load/Unload 
menu  item.  The  FDS  field  modeling  software  creates  this  file.  (See  Appendix  D.2  for  documentation  on  the 
format  of  this  file). 

The  character  occuring  before  a file  name  in  one  of  the  sub-menus  indicates  that  the  file  has  already 
been  loaded.  If  the  file  below  is  loaded  but  not  visible  then  use  the  appropriate  Show/Hide  option  to  make  it 
visible. 


Particle  File  ( .part)  This  menu  item  gives  the  name  of  the  particle  file  and  also  the  option  to  unload 
the  currently  loaded  particle  file. 

Slice  File  ( . sf ) This  menu  item  gives  the  name  of  all  slice  files  and  also  the  option  to  unload  the  cur- 

rently loaded  slice  file. 

PLOT3D  File  ( . q)  This  menu  item  gives  the  name  of  all  PFOT3D  files  and  also  the  option  to  unload 
the  currently  loaded  PFOT3D  file. 

Boundary  File  ( . bf ) This  menu  item  gives  the  name  of  all  boundary  files  and  also  the  option  to  unload 
the  currently  loaded  boundary  file. 

Init  File  ( . ini  ) The  init  or  preference  file  contains  configuration  parameters  that  may  be  used  to  cus- 
tomize Smokeview’s  appearance  and  behavior.  This  menu  item  lets  one  create  (or  overwrite) 
a preference  file  named  either  smokeview.  ini  or  casename  . ini.  A preference  file  con- 
tains parameter  settings  for  defining  how  Smokeview  visualizes  data.  This  file  may  be  edited 
and  re-read  while  Smokeview  is  running. 

Smokeview  input  file  ( . smv)  This  menu  item  is  used  when  debugging  FDS  input  files.  It  allows  one  to 
reload  a Smokeview  case  ( . smv  file).  A debugging  cycle  can  then  be  performed  consisting  of 
1)  editing  FDS  input  file,  2)  running  FDS  and  3)  reloading  an  updated  Smokeview  input  file. 

Unload  All  This  option  causes  all  data  files  to  be  unloaded. 


B.3  Show/Hide 

The  Show/Hide  menu  item  allows  one  to  show  or  hide  various  parts  of  the  simulation.  This  menu  item 
contains  sub-menus  for  Particles,  Boundary,  Animated  Slice,  PFOT3D  2D  and  3D  contours,  sensors  (ther- 
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mocouples,  heat  detectors  and  sprinklers).  Color  and  time  Bars  and  Geometry.  These  menu  items  only  appear 
if  they  pertain  to  the  simulation.  For  example  the  Particles  sub-menu  only  appears  if  a particle  file  has 
been  loaded.  Similarly,  the  PLOT3D  contouring  sub-menus  only  appear  if  a PLOT3D  file  has  been 
loaded.  The  “*”  character  is  used  to  indicate  whether  the  visualization  feature  corresponding  to  the  menu 
item  is  set  or  active. 

B.3.1  Geometry  Options 

Blockages  The  three  blockage  viewing  options  are  Show  All,  Show  Frame  and  Hide.  The  first  and 
last  option  are  self  explanatory.  The  Show  Frame  option  allows  one  to  view  only  a frame  or 
outline  of  each  blockage.  This  makes  it  easier  to  see  other  simulation  features  when  the  scenario 
has  many  blockages.  Blockages  may  be  displayed  in  different  colors.  This  allows  one  to  more 
easily  set  up  FDS  input  files  by  identifying  blockages  and  verifying  that  they  have  been  defined 
as  intended. 

Grid  This  option  allows  one  to  visualize  the  grid  used  to  perform  the  numerical  calculations.  One  se- 

lects xy  plane,  xz  plane  oryz  plane  to  visualize  a single  plane  or  Show  All,  Hide 
All  to  show  or  hide  all  grids.  (Keyboard  shortcut:  g) 

Outline  Show  or  hide  the  outline  that  frames  the  simulation  scene. 

Floor  Show  or  hide  the  floor. 

Vents  Show  or  hide  the  vents. 

Walls  Show  or  hide  the  walls. 

B.3.2  Particles 

Smoke  (tracer)  Toggle  the  visibility  of  the  particles.  If  water/sprinkler  droplets  are  present  in  the  particle 
file  then  sub-menus  exist  for  both  smoke  and  water  to  allow  one  to  show  or  hide  smoke  and 
water  droplets  independently. 

Sprinkler  Toggle  the  visibility  of  sprinkler  (water  droplets). 


B.3.3  Boundary 

Exterior  Show  or  hide  all  data  contained  in  a boundary  ( . bf ) file  pertaining  to  the  exterior  walls. 

Interior  Show  or  hide  all  data  contained  in  a boundary  ( . bf ) file  pertaining  to  interior  blockages. 

Front,  Back,  Left,  Right,  Up,  Down  Toggle  the  visibility  of  whatever  exterior  boundary  surface  is  se- 
lected. Note  an  exterior  boundary  menu  option  only  appears  if  its  data  is  present  in  the  boundary 
file. 


B.3.4  Animated  Slice 

Toggle  the  visibility  of  the  animated  slice  or  slice  file. 

B.3.5  PLOT3D  2D  Contours 

Solution  Variables  A PLOT3D  data  file  contains  five  solution  variables.  If  one  or  more  of  the  velocity 
components  denoted  u,  v and  w are  present  in  the  PLOT3D  file  then  speed,  calculated  using 
V u2  + v2  + u’2,  appears  in  the  menu.  Any  velocity  components  missing  from  the  PLOT3D  file 
are  set  to  0.0  when  calculating  speed.  This  menu  item  allows  one  to  select  the  PLOT3D  solution 
variable  to  be  visualized.  (Keyboard  shortcut:  p) 
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xy,  xz,  yz  planes  These  three  menu  items,  appearing  beneath  the  Solution  Variables  menu  item, 
allow  one  to  select  which  plane  (xy,  xz  or  yz)  is  displayed.  (Applicable  keyboard  shortcuts: 
space  bar,  -,  left/right  cursor,  up/down  cursor,  page  up/down,  1 . . .9) 

Flow  vectors  Toggle  visibility  of  flow  vectors.  The  magnitude  and  direction  of  the  vectors  are  deter- 
mined by  the  U,  V and  W components  of  velocity.  The  vector  color  is  determined  by  the 
solution  variable  selected.  (Applicable  keyboard  shortcuts:  a,  s , v) 

Continuous  Display  contours  as  smooth  continuous  shades  or  as  stepped  constant  shades.  (Keyboard 
shortcut:  c) 

Show  All  Show  all  three  (xy,  xz  and  yz)  PLOT3D  planes  at  once. 

Hide  All  Hide  all  three  PLOT3D  planes. 

B.3.6  PLOT3D  3D  Contours 

Solution  Variables  Same  as  for  2D  contours.  This  menu  item  allows  one  to  select  the  solution  variable 
used  to  generate  the  3D  or  iso-contour  to  be  displayed. 

Level  Select  the  3D  contour  level  to  display.  The  axis  label  shown  in  red  corresponds  to  the  3D 

contour  level  displayed. 

Block  Size  To  increase  the  drawing  speed,  adjacent  grid  cells  may  be  combined  when  viewing  3D  con- 
tours. Selecting  1 will  result  in  highly  resolved  contours  but  may  take  longer  to  draw.  Selecting 
5 will  have  the  opposite  effect. 

Hide  Hide  the  3D  contour. 


B.3.7  Heat  detectors.  Sprinklers,  Thermocouples 

Toggle  the  sensor  visibility.  The  currently  implemented  sensors  are  heat  detectors,  sprinklers  and  thermocou- 
ples. 

B.3.8  Shades 

Flip  Flip  the  background  color  between  a dark  and  light  shade.  A dark  background  shade  looks 

better  on  a computer  monitor  while  a light  shade  looks  better  on  the  printed  page. 

Color  Toggle  scene  colors  between  color  and  shades  of  gray.  This  option  currently  does  not  convert  all 

scene  colors  to  shades  of  gray.  It  was  felt  that  contours  and  blockages  were  the  most  important 
to  convert. 

Transparent  Toggle  contours  between  opaque  and  transparent.  Transparent  colors  allow  one  to  view  the 
scene  behind  the  contours  giving  the  one  a better  sense  of  scale.  Transparent  colors  however 
may  make  the  scene  look  too  confusing  when  the  geometry  is  complex. 


B.3.9  Rotation 

Eye  Centered  Rotate  and  move  the  scene  relative  to  the  observer’s  “eye”.  Eye  centered  views  make  it 
easier  to  move  around  within  the  scene  itself  as  in  modem  computer  games.  (Keyboard  shortcut: 
e.  The  “e”  keyboard  shortcut  toggles  the  view  between  an  eye  centered  and  a world  centered 
perspective.) 

World  Centered  Rotate  and  move  the  scene  relative  to  the  scene’s  center.  (Keyboard  shortcut:  e.  The 
“e”  keyboard  shortcut  toggles  the  view  between  an  eye  centered  and  a world  centered  perspec- 
tive.) 
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B.3.10  Labels 


Color  Bars,  Time  Bars,  Title,  Frame  Rate  Show  or  hide  the  individual  scene  element. 

Show  All  Show  all  scene  elements. 

Hide  All  Hide  all  scene  elements. 

C Keyboard  Commands 

Many  menu  commands  have  equivalent  keyboard  shortcuts.  These  shortcuts  are  described  here  and  are  also 
briefly  described  under  the  Help  menu  item  from  within  Smokeview  itself. 


a Alter  the  arrow  size  used  to  display  velocity  vectors. 

b To  increase  the  drawing  speed,  adjacent  grid  cells  may  be  combined  into  coarser  pseudo-grid 

cells  when  generating  and  viewing  3D  contours.  The  “b”  key  is  used  to  increment  the  number 
of  grid  cells  that  are  combined  (between  one  and  five  grid  cells)  when  generating  3D  contours. 
Using  one  grid  will  result  in  highly  resolved  contours  but  may  take  longer  to  draw.  Using  five 
grid  cells  will  have  the  opposite  effect,  i.e.  will  result  in  coarse  contours  that  can  be  drawn 
quickly. 

c Toggle  the  PLOT3D  2D  contour  display  between  solid  banded  contours  and  continuously  shaded 

contours. 

e Toggle  how  the  scene  is  manipulated  between  an  “eye  view”  where  scene  motion  is  relative  to 

the  observer  and  a “world  view”  where  the  scene  motion  is  relative  to  the  scene  center. 

g Toggle  the  grid  visiblity.  When  the  grid  display  option  is  active,  the  x,  y and  z keys  may  be  used 

to  show  or  hide  the  grid  perpendicular  to  the  x,  y and  z axes  respectively. 

i Toggle  the  visiblity  of  iso-contours  (3D  surface  contours). 

o Reset  a time  dependent  animation  to  the  initial  time. 

p Show  the  next  variable  in  the  PLOT3D  data  set. 

r Render  the  current  scene  as  a GIF  file  which  can  be  viewed  in  a web  browser  or  inserted  into  a 

word  processing  document. 

s Increment  the  number  of  vectors  skipped.  Useful  for  making  vector  displays  more  readable 

when  grids  are  finely  meshed. 

t Toggle  the  time  stepping  mode.  Time  stepping  mode  allows  one  to  step  through  the  simulation 

one  time  step  at  a time. 

x,  y,  z Toggle  the  visibility  of  the  PLOT3D  data  planes  perpendicular  to  the  x,  y and  z axes  respectively 

(parallel  to  the  yz,  xz  and  xy  planes). 

v Toggle  vector  visibility.  This  option  is  only  active  when  there  are  U,  V and/or  W velocity 

components  present  in  the  PLOT3D  data  set. 

Left/Right  Cursor  Incremenl/decrement  the  PLOT3D  plane  location  displayed  in  the  xz  plane. 

Page  Up,  Page  Down  Increment/decrement  the  PLOT3D  plane  location  displayed  in  the  xy  plane. 

Up/Down  Cursor  Increment/decrement  the  PLOT3D  plane  location  displayed  in  the  yz  plane. 

Decrement  PLOT3D  data  planes,  PLOT3D  iso-contour  levels  or  time  step  displayed. 

space  bar  Increment  PLOT3D  data  planes,  PLOT3D  iso-contour  levels  or  time  step  displayed. 
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D File  Formats 


D.l  Smokeview  Preference  File  Format  ( . ini  files) 

Smokeview  uses  preference  files  to  set  input  parameters  not  settable  using  menus  or  the  keyboard  and  to  save 
the  “state"  of  a visualization.  Smokeview  looks  for  preference  files  in  three  locations  in  the  following  order: 

1.  a file  named  smokeview.  ini  in  a global  directory  defined  by  the  SMOKEVIEWINI  environment 
variable.  On  the  PC,  the  directory  C : \nist\fds\smokeview.  ini  is  the  default  location  for  this 
preference  file.  The  SMOKEVIEWINI  environment  variable  may  be  defined  on  the  PC  by  adding  the 
line 

set  SMOKEVIEWINI =dir 

to  the  c:\autoexec.bat  file  where  dir  is  the  directory  where  the  global  customization  file  is 
stored.  This  step  is  performed  automatically  by  the  Smokeview  installation  program.  This  environ- 
ment variable  may  be  defined  on  a UNIX  workstation  by  adding  the  line 
setenv  SMOKEVIEWINI  dir 

to  a . login  or  .cshrc  start  up  file  again  where  dir  is  the  directory  containing  the  global  cus- 
tomization file.  Changes  to  this  smokeview.  ini  file  apply  to  all  cases  visualized  on  the  computer 
unless  overridden  by  preference  files  named  or  located  in  directories  named  in  steps  2.  and  3. 

2.  a file  named  smokeview.  ini  in  the  directory  containing  the  case  being  visualized.  Changes  to  this 
smokeview . ini  file  apply  to  all  cases  in  the  current  directory  unless  overridden  by  the  casename  . ini 
file  contained  in  this  directory. 

3.  a file  named  casename  . ini  in  the  directory  containing  the  case  being  visualized  where  casename  if 
the  name  of  the  case. 

The  smokeview.  ini  file  may  be  created  by  typing 
smokeview  -ini 

from  the  command  line  or  by  selecting  the  Write  smokeview.  ini  menu  item.  The  casename  . ini 
preference  file  can  be  created  via  the  menus  or  by  copying  a previously  created  smokeview . ini  file. 

Smokeview  reads  the  global  smokeview . ini  file  first  (step  1 . above),  followed  by  the  local  smokeview . ini 
file  (step  2.  above),  followed  by  the  casename  . ini  file.  The  global  smokeview.  ini  file  is  used  to  cus- 
tomize parameters  for  all  Smokeview  runs.  The  local  smokeview . ini  file  is  used  to  customize  parameters 
for  just  those  Smokeview  runs  contained  in  the  local  directory.  The  casename  . ini  file  is  used  to  customize 
parameters  for  only  those  Smokeview  runs  with  the  prefix  casename. 

All  preference  file  parameters  unless  otherwise  noted  consist  of  a KEYWORD  followed  by  a value,  as  in 

KEYWORD 

value 

D.1.1  Color  parameters 

All  colors  are  specified  using  a 3-tuple:  r g b where  r,  g and  b are  the  red,  green  and  blue  components  of  the 
color  respectively.  Each  color  component  is  a floating  point  number  ranging  from  0.0  to  1.0  where  0.0  is  the 
darkest  shade  and  1.0  is  the  lightest  shade.  For  example  the  3-tuple  1.0  0.0  0.0  is  bright  red,  0.0  0.0  0.0  is 
black  and  1.0  1.0  1.0  is  white. 


BACKGROUNDCOLOR  Sets  the  color  used  to  visualize  the  scene  background,  (default:  0.0  0.0 

0.0) 

BLOCKCOLOR  Sets  the  color  used  to  visualize  internal  blockages,  (default:  1.0  .8  4.0) 
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BOUNDCOLOR  Sets  the  color  used  to  visualize  floors,  walls  and  ceilings,  (default:  0.5  0.5  0.2) 

COLORBAR  Entries  for  the  color  palette  in  rgb  (red,  green,  blue)  format  where  each  color  component 
ranges  from  0.0  to  1.0.  The  default  values  (rounded  to  2 digits)  are  specified  with 


COLORBAR 

12 

0.00  0.00  1.00 
0.00  0.28  0.96 
0.00  0.54  0.84 
0.00  0.76  0.65 
0.00  0.91  0.41 
0.00  0.99  0.14 
0.14  0.99  0.00 
0.41  0.91  0.00 
0.65  0.76  0.00 
0.84  0.54  0.00 
0.96  0.28  0.00 
1.00  0.00  0.00 


COLOR2BAR  Miscellaneous  colors  used  by  Smokeview.  The  default  values  are  specified  using 


COLOR2BAR 

8 


1 . 0 

1.0 

1 . 0 

: white 

1 . 0 

1 . 0 

o 

o 

: yellow 

o 

o 

o 

o 

o 

: blue 

1.0 

o 

o 

o 

o 

: red 

o 

o 

1.0 

o 

o 

: green 

1 . 0 

o 

o 

1 . 0 

: magenta 

o 

o 

1.0 

1 . 0 

: cyan 

o 

o 

o 

o 

o 

o 

: black 

where  the  8 indicates  the  number  of  colors  defined  and  the  character  string  after  the  ' ' : ' ' are 
ignored. 

FOREGROUNDCOLOR  Sets  the  color  used  to  visualize  the  scene  foreground  (such  as  text  labels), 
(default:  1.0  1.0  1.0) 

SENSORCOLOR  Sets  the  color  used  to  visualize  sensors,  (default:  1.0  1.0  0.0) 

SETBW  The  parameter  used  to  set  whether  color  shades  (0)  or  shades  of  grey  ( 1 ) are  to  used  for  coloring 
contours  and  blockages,  (default:  0) 

SPRINKOFFCOLOR  Sets  the  color  used  to  visualize  sprinklers  before  they  activate,  (default:  1 . 0 

0.0  0.0) 

SPRINKONCOLOR  Sets  the  color  used  to  visualize  sprinklers  after  they  activate,  (default:  0.0  1.0 
0.0) 

VENTCOLOR  Sets  the  color  used  to  visualize  vents,  (default:  1.0  0.0  1.0) 
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D.1.2  Size  parameters 


The  parameters  described  in  this  section  allow  one  to  customize  the  size  of  various  Smokeview  scene  ele- 
ments. 


LINEWIDTH  Defines  the  width  of  lines  in  pixels  except  lines  used  to  draw  vents,  (default:  2.0) 
PARTPOINTSIZE  Defines  the  size  in  pixels  of  smoke  or  tracer  particles,  (default:  1 .0) 

SENSORABSSIZE  Defines  the  sensor  size  drawn  by  smokeview  using  the  same  units  as  used  to  specify 

the  grid  coordinates,  (default:  0.038) 

SLICEOFFSET  Defines  an  offset  distance  between  animated  slices  and  adjacent  solid  surfaces.  The 
offset  distance  is  relative  to  the  maximum  grid  cell  width,  (default:  0. 10) 

SPRINKLERABSSIZE  Defines  the  sprinkler  size  drawn  by  smokeview  using  the  same  units  as  used  to 
specify  the  grid  coordinates,  (default:  0.076) 

VECTORLENGTH  Defines  the  length  of  PLOT3D  vectors.  A vector  length  of  1 .0  fills  one  grid  cell. 

Vector  lengths  may  also  be  changed  from  within  Smokeview  by  depressing  the  “a”  key.  (de- 
fault: 4.0) 

VECTORPOINTSIZE  Defines  the  size  in  pixels  of  the  point  that  is  drawn  at  the  end  of  a PLOT3D 
vector,  (default:  3.0) 

VENTLINEWIDTH  Defines  the  width  of  lines  used  to  draw  vents  in  pixels,  (default:  2.0) 

VENTOFFSET  Defines  a distance  used  to  offset  vents  drawn  from  adjacent  surfaces,  (default:  0.10 
(units  of  fraction  of  a grid  cell  width)) 

WINDOWHEIGHT  Defines  the  initial  window  height  in  pixels,  (default:  480) 

WINDOWWIDTH  Defines  the  initial  window  width  in  pixels,  (default:  640) 

D.1.3  Time  and  value  bound  parameters 

This  section  describes  parameters  used  by  Smokeview  to  1)  modify  the  time  intervals  used  to  load  data 
(keywords  beginning  with  T_ ) and  2)  over-ride  the  minimum  and  maximum  data  values  (keywords  beginning 
with  V_)  used  to  convert  data  to  color  values.  By  default,  Smokeview  reads  in  data  for  all  time  values  and 
does  not  over-ride  minimum  and  maximum  data  values.  Each  time  and  data  bound  keyword  (except  for 
V_PLOT3D)  has  the  format 

KEYWORD 

minflag  minvalue  maxflag  maxvalue 

where  minflag  can  be  either  0 or  1.  If  it  is  1 then,  the  subsequent  number,  minvalue  is  used  by  Smoke- 
view to  scale  the  data  otherwise  if  minflag  is  0 then  minvalue  is  ignored.  The  next  two  parameters 
maxflag  and  maxvalue  are  defined  similarly.  The  V_PLOT3D  keyword  contains  data  bound  entries  for 
each  variable  in  the  PLOT3D  data  file.  If  a PLOT3D  “speed”  variable  was  constructed  by  Smokeview  then 
the  V_PLOT3D  keyword  will  contain  six  entries  instead  of  five. 


T_BOUNDARY  Defines  the  minimum  and  maximum  times  used  to  include  particles  in  a visualization. 
The  default  values  are  specified  with 


T_BOUNDARY 
0 1.0  0 0.0 
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To  load  boundary  data  between  20  and  150  seconds  use 


T_B  OUNDAR Y 
1 20.  1 150. 

T_PARTICLES  Defines  the  minimum  and  maximum  times  used  to  include  particles  in  a visualization, 
(default:  0 1.0  0 0.0) 

T_SLICE  Defines  the  minimum  and  maximum  times  used  to  include  particles  in  a visualization,  (de- 
fault: 0 1.0  0 0.0) 

V_BOUNDARY  Defines  the  minimum  and  maximum  data  bounds  used  to  convert  boundary  data  values 
to  color  indices,  (default:  0 1.0  0 0.0) 

V_PARTICLES  Defines  the  minimum  and  maximum  data  bounds  used  to  convert  particle  data  values 
to  color  indices,  (default:  0 1.0  0 0.0) 

\TPLOT3D  Defines  the  minimum  and  maximum  data  bounds  used  to  convert  PLOT3D  data  values  to 
color  indices.  The  default  values  are  given  by 

V_PLOT3D 

5 

1 0 1.0  0 0.0 

. 2 0 1.0  0 0.0 

3 0 1.0  0 0.0 

4 0 1.0  0 0.0 

5 0 1.0  0 0.0 

where  the  initial  5 indicates  the  number  of  subsequent  entries,  the  first  integer  on  each  line 
indicates  the  PLOT3D  data  variable  being  specified  and  all  other  parameters  on  each  line  are 
defined  as  above. 

V_SLICE  Defines  the  minimum  and  maximum  data  bounds  used  to  convert  slice  data  values  to  color 
indices,  (default:  0 1.0  0 0.0) 


D.1.4  Data  loading  parameters 

The  keywords  in  this  section  may  be  used  to  reduce  the  memory  required  to  visualize  FDS  data.  Keywords 
exist  for  limiting  particles  and  frames.  Other  keywords  exist  for  compressing  particle  data  and  skipping 
particles  and  frames. 


BOUNDFRAMESTEP  Defines  the  number  of  intervals  or  steps  between  loaded  boundary  file  frames, 
(default:  1) 

MAXFRAMES  Specifies  the  maximum  number  of  particle  frames  that  can  be  read  in.  (default:  501) 

MAXPOINTS  Specifies  the  maximum  number  of  particle  points  that  can  be  read  in  from  a particle  file, 
(default:  50000  00) 

NOPART  Indicates  that  a particle  file  should  not  ( 1 ) or  should  (0)  be  loaded  when  Smokeview  starts  up. 

This  option  is  used  when  one  wants  to  look  at  other  files  besides  the  particle  file,  (default:  0) 
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PARTFRAMESTEP  Specifies  the  interval  or  steps  between  loaded  particle  frames.  A particle  frame 
is  all  the  particles  loaded  at  one  particular  time  step.  For  example,  if  PARTFRAMESTEP  is  set 
to  3 then  every  3rd  particle  frame  is  read  in.  This  and  the  PARTPOINTSTEP  options  may  be 
used  together  to  dramatically  reduce  the  memory  required  to  view  particle  files.  These  options 
should  be  used  when  displaying  Smokeview  files  on  computers  with  limited  memory,  (default: 

1) 

PARTPOINTCOMPRESS  Specifies  how  Smokeview  stores  particle  data.  Each  particle  is  represented 

using  three  position  coordinates  and  one  data  value.  Using  full  precision  (PARTPOINTCOMPRESS 
value  of  0),  Smokeview  uses  four  bytes  per  position  coordinate  and  one  byte  for  the  data  value 
or  13  bytes  to  represent  each  particle  point.  If  this  keyword  is  set  to  1 then  Smokeview  uses 
one  byte  per  position  coordinate  and  one  byte  for  the  data  value  or  4 bytes  per  particle  point. 
Finally  if  this  keyword  has  value  2 then  2 bytes  are  used  to  store  each  position  coordinate  and 
one  byte  for  the  data  value  or  7 bytes  per  particle  point,  (default:  2)  The  recommended  value  is 
2.  Using  0 results  in  almost  twice  the  memory  usage  without  any  extra  precision  in  positioning 
particles.  Using  1.  though  using  less  memory  than  the  “2”  option,  results  in  granularity  effects 
when  displaying  particles  which  one  may  find  annoying,  (default:  2) 

PARTPOINTSTEP  Specifies  the  interval  or  steps  between  loaded  particle  points.  For  example,  if 
PARTPOINTSTEP  is  set  to  5 then  every  5th  particle  or  only  20  % of  the  particle  file  is  read  in. 
(default:  1) 

SLICEFRAMESTEP  Specifies  the  number  of  interval  or  steps  between  loaded  slice  file  frames,  (de- 
fault: 1) 


D.1.5  Viewing  parameters 

The  keywords  in  this  section  define  how  a scene  is  viewed.  Keywords  exist  for  showing  or  hiding  various 
scene  elements  and  for  modifying  how  various  scene  elements  appear. 


AXISNUM  Specifies  whether  Smokeview  should  (AXISNUM  set  to  1)  or  should  not  (AXISNUM  set  to 

0)  calculate  data  minimums  and  maximums  based  upon  statistical  limits.  For  example,  if  this 
parameter  is  set  to  1 then  Smokeview  will  set  the  minimum  and  maximum  data  bound  to  be  the 
1st  and  99th  percentile  of  the  data  respectively,  (default:  1) 

AXISSMOOTH  Specifies  whether  axis  numerical  labels  should  be  smoothed  (AXISSMOOTH  set  to 

1)  or  not  smoothed  (AXISSMOOTH  set  to  0).  (default:  1 ) 

EYEVIEW  Specifies  whether  the  scene  should  be  rotated  relative  to  the  observer  (EYEVIEW  set  to  1) 
or  the  scene  center  (EYEVIEW=0).  (default:  0) 

EYEX,  EYEY,  EYEZ  The  parameters  EYEX,  EYEY,  EYEZ  specify  the  x,  y and  z location  respec- 
tively of  the  viewing  origin  (where  your  eyes  are),  (default:  0.5  -0.9  1.5) 

FRAMERATEVALUE  Specifies  the  maximum  rate  (frames  per  second)  that  Smokeview  should  display 
frames.  This  value  is  an  upper  bound.  Smokeview  will  not  display  frames  faster  than  this  rate 
but  may  display  frames  at  a slower  rate  if  the  scene  to  be  visualized  is  complex,  (default: 
1000000) 

P3CONT2D  The  parameter  P3CONT2D  may  be  set  to  0,  1 or  2.  If  P3CONT2D  is  set  to  0 then  PLOT3D 
color  contours  are  drawn  by  coloring  each  node  and  letting  OpenGL  interpolate  colors  be- 
tween nodes.  If  P3CONT2D  is  set  to  1 then  discrete  or  stepped  shaded  contours  are  drawn.  If 
P3CONT2D  is  set  to  2 then  contour  lines  are  drawn,  (default:  1) 

SHOWBLOCKS  Specifies  how  a blockage  should  be  drawn.  A value  of  0,  1 or  2 indicates  that  the 
blockages  are  invisible,  drawn  normaly  or  drawn  as  outlines  respectively,  (default:  1) 
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SHOWCEILING  Specifies  whether  the  ceiling  (upper  bounding  surface)  should  be  drawn  (1)  or  not 
drawn  (0).  (default:  0) 

SHOWCOLORBARS  Specifies  whether  the  color  bars  should  be  drawn  ( 1 ) or  not  drawn  (0)  (default: 

1) 

SHOWFLOOR  Specifies  whether  the  floor  (lower  bounding  surface)  should  be  drawn  ( 1 ) or  not  drawn 
(0)  (default:  1) 


SHOWFRAMERATE  Specifies  whether  the  frame  rate  label  should  be  drawn  (1)  or  not  drawn  (0). 
(default:  1) 

SHOWSMOKEPART  Specifies  whether  smoke  or  trace  particles  should  be  drawn  ( 1 ) or  not  drawn  (0) 
(default:  1) 

SHOWSPRINKPART  Specifies  whether  sprinkler  droplet  particles  (if  present  in  the  particle  file)  should 
be  drawn  ( 1 ) or  not  drawn  (0).  (default:  1 ) 

SHOWTIMEBAR  Specifies  whether  the  timebar  should  be  drawn  (1)  or  not  drawn  (0).  (default:  1 ) 

SHOWTITLE  Specifies  whether  the  title  should  be  drawn  (1)  or  not  drawn  (0).  (default:  I ) 

SHOWWALLS  Specifies  whether  the  four  walls  (four  vertical  bounding  surfaces)  should  be  drawn  ( 1 ) 
or  not  drawn  (0).  (default:  1) 


TRANSPARENT  Specifies  whether  2D  and  3D  contours  should  be  drawn  with  solid  colors  (0)  or  trans- 
parent colors(  1 ).  (default:  1 ) 

VECTORSKIP  Specifies  what  vectors  to  draw.  For  example,  if  this  parameter  is  set  to  2 then  every  2nd 
vector  is  drawn  when  displaying  vectors,  (default:  1) 


D.2  Smokeview  Parameter  Input  File  ( . smv  file) 

The  FDS  software  outputs  simulation  results  into  the  Smokeview  input  file  with  extension  . smv  and  various 
output  data  files  whose  format  is  documented  in  the  next  section.  A . smv  file  is  a formatted  ascii  file  (ie.  a 
regular  text  file)  consisting  of  a set  of  KEYWORD  followed  by  DATA  describing  an  FDS  case’s  geometry, 
file  name  and  contents,  sensor  information  etc. 

D.2.1  Geometry  Keywords 

OBST  The  keyword  specifies  internal  blockages.  A FORTRAN  90  code  segment  describing  the  format 
of  OBST  data  is  given  by 


read ( 5 , * ) nb 
do  i = 1 , nb 

read ( 5 , * ) dummy 
end  do 

do  i = 1,  nb 

read ( 5 , * ) ibl ( i ) , ib2(i),  jbl(i),  jb2(i),  kbl ( i ) , kb2 ( i ) 
end  do 

where  ibl , ib2  , jbl,  kbl,  kb2  are  integer  arrays  containing  boundary  nodes. 

TRNX,TRNY,TRNZ  TheTRNX,  TRNY,  TRNZ  keywords  specify  grid  nodes  in  the  X,  Y,  Z coor- 
dinate directions.  A FORTRAN  90  code  segment  describing  the  format  of  TRNX  data  is  given 
by 
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nx 


read ( 5 , * ) 
do  i = 1 , nx 

read ( 5 , x) idumray 
end  do 

do  i = 1 , nx 

read ( 5 , * ) xplt ( i ) 
end  do 


TRNY  and  TRNZ  data  entries  are  defined  similarly.  The  first  nx  data  items  are  not  required  by 
Smokeview. 

VENT  The  keyword  specifies  vent  coordinates.  A FORTRAN  90  code  segment  describing  the  format 
of  VENT  data  is  given  by 

read ( 5 , * ) nv 
do  i = 1 , nv 

read ( 5 , * ) dummy 
end  do 

do  i = 1 , nv 

read ( 5 , * ) ivl ( i ) , iv2(i),  jvl(i),  jv2(i),  kvl(i),  kv2(i) 
end  do 

where  ivl , iv2  , jvl,  kvl , kv2  are  integer  arrays  containing  vent  coordinates. 

XYZ  The  XYZ  keyword  defines  the  .xyz  or  PLOT3D  grid  file  name.  A FORTRAN  90  code  segment 

describing  the  format  of  XYZ  data  is  given  by 


read ( 5 , " ( a ) " ) xyz  f i 1 ename 


where  xyz  filename  is  a character  variable  containing  the  name  of  the  .xyz  file. 


D.2.2  File  Keywords 

BNDF  The  BNDF  keyword  defines  the  . bf  file  name  along  with  character  labels  used  to  describe  the 
data  contents  of  the  boundary  file.  A FORTRAN  90  code  segment  describing  the  format  of 
BNDF  data  is  given  by 


read ( 5 , ' 

' (a)  1 

' ) longlabel 

read ( 5 , ' 

' (a)  ' 

' ) shortlabel 

read ( 5 , ' 

' (a)  1 

' ) unit 

where  longlabel , shortlabel , unit  are  character  variables  of  length  30. 

PART  The  PART  keyword  defines  the  .part  file  name  along  with  character  labels  used  to  describe 
the  data  contents  of  the  particle  file.  A FORTRAN  90  code  segment  describing  the  format  of 
PART  data  is  given  by 
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read ( 5 , " (a) " ) longlabel 
read ( 5 , " (a) " ) short label 
read ( 5 , " ( a ) " ) unit 


where  longlabel , shortlabel , unit  are  character  variables  of  length  30. 

PL3D  The  PL3D  keyword  defines  the  . q file  name  along  with  character  labels  used  to  describe  the 
data  contents  for  each  PLOT3D  variable.  A FORTRAN  90  code  segment  describing  the  format 
of  PL3D  data  is  given  by 


* i = 

read  i 

1,  5 
(5, " (a) 

" ) longlabel ( i ) 

read  i 

(5,  " (a) 

" ) shortlabel ( i 

read  i 

15,  " (a) 

" ) unit ( i ) 

end  do 

where  the  character  arrays  longlabel , shortlabel , unit  each  have  length  30. 

SLCF  The  SLCF  keyword  defines  the  . sf  file  name  along  with  character  labels  used  to  describe  the 
data  contents  of  the  slice  file.  A FORTRAN  90  code  segment  describing  the  format  of  SLCF 
data  is  given  by 


read ( 5 , " ( a ) " ) longlabel 
read ( 5 , " (a) " ) shortlabel 
read ( 5 , " ( a ) " ) uni t 

where  longlabel , shortlabel , unit  are  character  variables  of  length  30. 


D.2.3  Sensor  Keywords 

HEAT  The  HEAT  keyword  defines  heat  detector  location  data.  A FORTRAN  90  code  segment  describ- 
ing the  format  of  HEAT  data  is  given  by 


read ( 5 , * ) nheat 
do  i = 1 , nheat 

read ( 5 , * ) xheat ( i ) , yheat ( i ) , zheat ( i ) 
end  do 


where  nheat  is  the  number  of  heat  detectors  and  xheat , yheat , zheat  are  the  x , y , 
z coordinates  of  the  heat  detectors. 

HEAT_ACT  The  HEAT  ACT  keyword  defines  heat  detector  activation  data.  A FORTRAN  90  code  seg- 

ment describing  the  format  of  HEAT  ACT  data  is  given  by 


read ( 5 , * ) iheat , heat_time 
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where  heat_time  is  the  activation  time  of  the  iheat’th  heat  detector. 

SPRK  The  SPRK  keyword  defines  sprinkler  location  data.  A FORTRAN  90  code  segment  describing 
the  format  of  SPRK  data  is  given  by 


read ( 5 , * ) nsprink 
do  i = 1 , nsprink 

read ( 5 , * ) xsprink ( i ) , ysprink ( i ) , zsprink ( i ) 
end  do 


where  nsprink  is  the  number  of  sprinklers  and  xsprink,  ysprink,  zsprink  are  the 
x,  y,  z coordinates  of  the  sprinklers. 

SPRK_ACT  The  SPRKJVCT  keyword  defines  sprinkler  activation  data.  A FORTRAN  90  code  segment 
describing  the  format  of  SPRK.ACT  data  is  given  by 


read ( 5 , * ) isprink,  sprink_time 


where  sprink.time  is  the  activation  time  of  the  isprink'th  sprinkler. 

THCP  The  THCP  keyword  defines  thermocouple  location  data.  A FORTRAN  90  code  segment  de- 
scribing the  format  of  THCP  data  is  given  by 


read ( 5 , * ) ntherm 
do  i = 1,  ntherm 

read ( 5 , * ) x therm ( i ) , y therm ( i ) , z therm ( i ) 
end  do 


where  ntherm  is  the  number  of  thermocouples  and  xtherm,  y therm,  z therm  are  the 
x,  y,  z coordinates  of  the  thermocouples. 


D.2.4  System  Keywords 

ENDIAN  The  ENDIAN  keyword  defines  whether  a big  or  little  endian5  system  is  used  to  represent  the 
data.  The  PC  (both  Windows  and  LINUX)  uses  the  little  endian  system  for  representing  num- 
bers while  most  UNIX  workstations  use  the  big  endian  system.  The  PC  version  of  Smokeview 
uses  this  keyword  to  determine  whether  data  should  be  converted  between  these  two  systems 
before  it  is  visualized.  The  valid  ENDIAN  paramters  are  BIG  or  LITTLE. 

SYST  The  SYST  keyword  defines  which  system  the  FDS  case  was  run  on.  The  PC  version  of  Smoke- 
view  uses  this  information  (if  the  ENDIAN  keyword  is  absent)  to  swap  data  bytes  if  the  FDS 
case  was  run  on  a computer  with  a different  “endian”  format  than  the  PC. 


5Big-endian  and  little-endian  are  terms  that  describe  the  order  in  which  a sequence  of  bytes  are  stored  in  computer  memory.  Big- 
endian  is  an  order  in  which  the  big  end  (most  significant  value  in  the  sequence)  is  stored  first  (at  the  lowest  storage  address).  Little-endian 
is  an  order  in  which  the  litde  end  (least  significant  value  in  the  sequence)  is  stored  first.  The  terms  big-endian  and  little-endian  are  derived 
from  the  Lilliputians  of  Gulliver's  Travels,  whose  major  political  issue  was  whether  soft-boiled  eggs  should  be  opened  on  the  big  side  or 
the  little  side. 
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D.3  Data  File  Formats  (. part,  . sf,  . bf  and  . q files) 

Smokeview  visualizes  fire  dynamics  data  using  particle,  boundary,  slice  and  PLOT3D  data  files  described 
in  this  section  along  with  a Smokeview  parameter  input  file  described  in  the  previous  section.  This  section 
documents  the  data  format  of  each  data  file  by  showing  FORTRAN  program  code  segments  used  to  write  the 
data  out.  All  files  are  unformatted  and  are  opened  using  OPEN  statments  of  the  form 

OPEN ( UNIT=IUNIT , F I LE= FILENAME , FORM= " UNFORMATTED " ) 

where  IUNIT  is  the  FORTRAN  unit  number  used  for  output  and  FILENAME  is  a character  variable  contain- 
ing the  file  name.  In  the  following  code  segments  the  standard  FORTRAN  naming  convention  of  associating 
variables  beginning  with  I through  N to  integer  variables  and  all  other  alphabetic  characters  to  REAL  vari- 
ables is  used.  It  is  assumed  that  all  variables  take  up  four  bytes.  Variables  having  DUMMY  in  the  name 
indicates  that  they  are  not  used  by  Smokeview. 


D.3.1  Particle  File  Format 

Particle  files  are  used  to  store  smoke/tracer  particles  and/or  sprinkler  droplet  information.  The  particle  file 
consists  of  a header  and  a series  of  particle  frames.  Each  frame  contains  particle/droplet  positions  and  data 
values  for  each  particle  in  that  frame.  The  FDS  software  outputs  particle  frames  at  fixed  time  intervals  but 
there  is  no  requirement  by  Smokeview  for  this  to  happen.  Smokeview  reads  in  the  data  one  frame  at  a time 
noting  the  time  read  in  for  each  frame.  The  header  can  be  described  using  the  code  segment 


WRITE (IUNIT) 
WRITE (IUNIT) 
WRITE (IUNIT) 
WRITE (IUNIT) 
DO  N=1 , NB 


DUMMY , DUMMY , DUMMY , I PART , NPPS 
I BAR, JBAR, KBAR 

(DUMMY, 1=0, IBAR) , ( DUMMY , J= 0 , JBAR ) , ( DUMMY , K= 0 , KBAR ) 
NB 


WRITE (IUNIT)  IB1 (N) , IB2 (N) , JB1 (N) , JB2 (N) , KB1 (N) , KB2 (N) , 1 
END  DO 

WRITE (IUNIT)  NV 
DO  N=1,NV 


WRITE (IUNIT)  IV1 (N) , IV2 (N) , JV1 (N) , JV2 (N) , KVl (N) , KV2 (N) , 2 
END  DO 

WRITE (IUNIT)  NSPR 
DO  N=1 , NSPR 

WRITE ( IUNIT ) XSPO (N) , YSPO (N) , ZSPO (N) 

END  DO 


where  DUMMY  is  written  by  FDS  but  not  needed  by  Smokeview,  I PART  is  the  index  of  the  scalar  quantity 
associated  with  the  particles,  NPPS  is  the  maximum  number  of  particles  per  frame,  IBl , IB2  , etc  are  the 
indices  of  blocked  grid  cells,  IVl , IV2  , etc  indicate  vent  cell  nodes,  and  XSPO  , YSPO  , ZSPO  are  the 
coordinates  of  the  sprinklers.  Grid  coordinates  are  obtained  by  Smokeview  from  the  Smokeview  parameter 
input  file.  A particle  frame  is  written  using 

WRITE ( IUNIT ) TIME , NP , IDUMMY , ( ISPR (N) , N=1 , NSPR) 

WRITE (IUNIT)  (XP(I) , 1=1, NP) , 

( YP ( I ) , 1=1, NP) , 

(ZP(I) , 1=1, NP) , 

( BP ( I ) , 1=1, NP) 

IF  (NASPR.GT.O)  THEN 
WRITE (IUNIT)  NSP 

WRITE (IUNIT)  (XSP(I) ,1=1, NSP) , (YSP(I) ,1=1, NSP) , (ZSP(I) ,1=1, NSP) 
END  IF 
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where  NP  is  the  number  of  particles  in  this  frame,  ISPR  denotes  whether  the  sprinkler  has  activated,  NSPR  is 
the  number  of  sprinklers,  XP , YP , ZP  are  the  particle  coordinates,  BP  is  the  particle  value,  NAS  PR  is  the 
number  of  active  sprinklers,  NSP  is  the  number  of  sprinkler  droplets,  and  XSP , YSP , ZSP  are  the  droplet 
coordinates. 


D.3.2  Slice  File  Format 

Slice  files  are  unformatted.  The  slice  file  header  is  written  out  using 

WRITE (IUNIT)  C DUMMY 
WRITE (IUNIT)  C DUMMY 
WRITE (IUNIT)  C DUMMY 
WRITE (IUNIT)  II, 12, Jl, J2,K1,K2 

where  C DUMMY  is  character  strings  of  length  30.  Smokeview  obtains  this  information  from  the  Smokeview 
parameter  input  file  and  not  from  the  slice  file.  The  sextuple  (II , 12  , Jl , J2  , K1 , K2 ) denotes  the  bounding 
grid  cell  nodes  of  the  slice  to  be  displayed.  The  sextuple  indices  correspond  to  grid  cell  nodes,  or  corners,  thus 
the  entire  grid  would  be  represented  by  the  sextuple  (0  , IBAR,  0 , JBAR,  0 , KBAR).  The  grid  node  positions 
are  obtained  from  the  Smokeview  parameter  input  file. 

The  FDS  software  outputs  slice  frames  at  fixed  time  intervals  but  there  is  no  requirement  by  Smokeview 
for  this  to  happen.  Each  slice  frame  is  written  using 


WRITE (IUNIT)  TIME 

WRITE (IUNIT)  ( ( (QQ (I, J, K) , 1=11,12 ) , J= Jl , J2 ) , K=Kl , K2 ) 


where  TIME  is  the  time  in  seconds  when  the  data  is  ouput  and  QQ  are  the  data  values. 


D.3.3  Boundary  Files 

The  boundary  files  are  unformatted.  The  header  is  written  out  using 
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WRITE (IUNIT)  QUANTITY 
WRITE ( IUNIT ) SHORT_NAME 
WRITE (IUNIT)  UNITS 
WRITE (IUNIT)  NPATCH 
DO  10  1=1, NPATCH 

WRITE (IUNIT)  IP1 ( I ) , IP2 
CONTINUE 


I) , JP1 (I) , JP2 (I) , KP1 (I 


, KP2 (I) 


where  QUANTITY,  SHORT _NAME  and  UNITS  are  character  strings  of  length  30,  NPATCH  is  the  number 
of  planes  (or  "patches”)  that  make  up  the  solid  boundaries  plus  the  external  walls.  The  sextuple  arrays 
(I PI , IP2  , JP1 , JP2  , KPl , KP2)  defines  the  cell  nodes  of  each  patch.  The  user  does  not  prescribe  these. 

The  FDS  software  outputs  boundary  frames  at  fixed  time  intervals  but  there  is  no  requirement  by  Smoke- 
view for  this  to  happen.  The  boundary  file  frame  is  written  using 


WRITE (IUNIT)  TIME 
DO  10  1=1, NPATCH 

WRITE (IUNIT)  ( ( (QQ(I,J,K) , I=IP1(I) ,IP2(I) ) ,J=JP1(I) , JP2 ( I ) ) , K=KPl ( I ) , KP2 ( I ) ) 
10  CONTINUE 
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D.3.4  PLOT3D  Data 


Field  data  is  dumped  periodically  by  FDS  in  a format  used  by  the  graphics  package  PLOT3D[6].  The 
PLOT3D  data  sets  are  single  precision  (32  bit  reals),  whole  and  unformatted.  Note  that  there  is  blanking, 
that  is,  blocked  out  data  points  are  not  plotted.  The  grid  data  is  written  out  to  a file  called  casename  . xyz 
using 


WRITE ( I UNIT ) IBAR+1 , JBAR+1 , KBAR+1 

WRITE (IUNIT)  ( ( (X { I ) , 1 = 0, IBAR)  , J=0 , JBAR)  , K=  0 , KBAR ) , 

( ( ( Y ( J ) ,1  = 0, IBAR)  , J=0, JBAR)  , K=  0 , KBAR ) , 

( ( (Z (K)  , 1 = 0, IBAR)  , J=0, JBAR)  , K=  0 , KBAR ) , 

( ( ( IBLK ( I , J, K) , 1=0 , IBAR) , J=0, JBAR) , K=0 , KBAR) 

where  IBAR+1 , JBAR+1 , KBAR+1  are  the  number  of  grid  cells  along  the  I , J,  K coordinate  direc- 
tions, X,  Y and  Z are  the  physical  coordinates  of  the  cell  corners,  and  IBLK  is  an  indicator  of  whether  or 
not  the  cell  is  blocked.  If  the  point  (X,  Y,  Z)  is  completely  embedded  within  a solid  region,  then  IBLK  is  0. 
Otherwise,  IBLK  is  1 . The  flow  variables  are  written  to  a file  using 

WRITE ( IUNIT)  IBAR+1 , JBAR+1 , KBAR+1 
WRITE (IUNIT)  ZERO, ZERO, ZERO, ZERO 

WRITE (IUNIT)  ( ( ( (QQ(I, J,K,N) , 1=0, IBAR) , J=0, JBAR) , K=0 , KBAR) ,N=1, 5) 

The  five  channels  N=1 , 5 are  by  default  the  temperature  (C),  the  u,  v and  vv  components  of  the  velocity  (m/s), 
and  the  heat  release  rate  per  unit  volume  (kW/m3). 
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